Configuring SIP Message Manipulation

The Message Manipulations table lets you configure up to 500 Message Manipulation rules. A Message Manipulation rule defines a manipulation sequence for SIP messages. SIP message manipulation enables the normalization of SIP messaging fields between communicating network segments. For example, it allows service providers to design their own policies on the SIP messaging fields that must be present before a SIP call enters their network. Similarly, enterprises and small businesses may have policies for the information that can enter or leave their networks for policy or security reasons from a service provider. SIP message manipulations can also be implemented to resolve incompatibilities between SIP devices inside the enterprise network.

Each Message Manipulation rule is configured with a Manipulation Set ID. You can create groups (sets) of Message Manipulation rules by assigning each of the relevant Message Manipulation rules to the same Manipulation Set ID. The Manipulation Set ID is then used to assign the rules to specific calls:

■ Message manipulation rules can be applied pre- or post-classification:
● Pre-classification Process: Message manipulation can be done on incoming SIP dialog-initiating messages (e.g., INVITE) prior to the classification process. You configure this by assigning the Manipulation Set ID to the SIP Interface on which the call is received (see Configuring SIP Interfaces).
● Post-classification Process: Message manipulation can be done on inbound and/or outbound SIP messages after the call has been successfully classified. Manipulation occurs only after the routing process - inbound message manipulation is done first, then outbound number manipulation (see Configuring IP-to-IP Outbound Manipulations), and then outbound message manipulation. For viewing the call processing flow, see Call Processing of SIP Dialog Requests. You configure this by assigning the Manipulation Set ID to the relevant IP Group in the IP Groups table (see Configuring IP Groups).
■ SIP requests initiated by the device: You can apply Message Manipulation rules to SIP requests that are initiated by the device, for example, SIP REGISTERs for certain entities (e.g., Accounts) and keep-alive by SIP OPTIONS. If the destination of the request is an IP Group, then the device uses the Inbound and Outbound Manipulation Sets that are assigned to the IP Group. If there is no IP Group for the destination or the IP Group is not assigned an Inbound or Outbound Manipulation Set, then the global parameters [GWInboundManipulationSet] or [GWOutboundManipulationSet] are used. The [GWInboundManipulationSet] parameter defines the Message Manipulation Set that is applied to incoming responses for requests that the device initiated. The [GWOutboundManipulationSet] parameter defines the Message Manipulation Set that is applied to outgoing requests that the device initiates.

The device also supports a built-in SIP message normalization feature that can be enabled per Message Manipulation rule. The normalization feature removes unknown SIP message elements before forwarding the message. These elements can include SIP headers, SIP header parameters, and SDP body fields.

The SIP message manipulation feature supports the following:

■ Manipulation on SIP message type (Method, Request/Response, and Response type)
■ Addition of new SIP headers
■ Removal of SIP headers ("black list")
■ Modification of SIP header components such as values, header values (e.g., URI value of the P-Asserted-Identity header can be copied to the From header), call's parameter values
■ Deletion of SIP body (e.g., if a message body is not supported at the destination network this body is removed)
■ Translating one SIP response code to another
■ Topology hiding (generally present in SIP headers such as Via, Record Route, Route and Service-Route).
■ Configurable identity hiding (information related to identity of subscribers, for example, P-Asserted-Identity, Referred-By, Identity and Identity-Info)
■ Multiple manipulation rules on the same SIP message
■ Apply conditions per rule - the condition can be on parts of the message or call’s parameters
■ Apply Message Manipulation Set twice on SIP REGISTER messages -- first on the initial incoming unauthenticated REGISTER, and then again on the incoming authenticated SIP message received after the device sends a SIP 401 response for challenging the initial REGISTER request. For more information and for enabling this feature, see the [AuthenticatedMessageHandling] parameter.
■ Multiple manipulation rules using the same condition. The following figure shows a configuration example where Rules #1 and #2 ('Row Rule' configured to Use Previous Condition) use the same condition as configured for Rule #0 ('Row Rule' configured to Use Current Condition). For more information, see the description of the 'Row Rule' parameter in this section.

The following figure illustrates an example of a SIP message that is manipulated by the device as follows:

1. Removes the "Unknown_header: unknown_value" in the incoming message.
2. Changes the P-Asserted-Identity header value to "sip:200@10.33.216.1" in the outgoing message.

This manipulation example is done by configuring two Message Manipulation rules, where Rule #1 is assigned to the source IP Group and Rule #2 to the destination IP Group.

Parameter

Rule 1

Rule 2

Message Type

Invite.request

Invite.request

Condition

Header.Unkown_header !contains 'unknown_value'

Header.P-Asserted-Identity.URL.User == 'Susan'

Action Subject

Header.Unkown_header

Header.P-Asserted-Identity

Action Type

Remove

Modify

Action Value

 

'<sip:200@212.3.216.1>'
● For a detailed description of the syntax used for configuring Message Manipulation rules, refer to the document SIP Message Manipulation Reference Guide (click here).
● Inbound message manipulation is done only after the Classification, inbound and outbound number manipulation, and routing processes.
● Each message can be manipulated twice - on the source leg and on the destination leg (i.e., source and destination IP Groups).
● Unknown SIP parts can only be added or removed.
● SIP manipulations do not allow you to remove or add mandatory SIP headers. They can only be modified and only on requests that initiate new dialogs. Mandatory SIP headers include To, From, Via, CSeq, Call-Id, and Max-Forwards.
● The IP Group's 'SIP Group Name' parameter overrides inbound message manipulation rules that manipulate the host name in Request-URI, To, and/or From SIP headers. If you configure a SIP Group Name for the IP Group (see Configuring IP Groups) and you want to manipulate the host name in these SIP headers, you must apply your manipulation rule (Manipulation Set ID) to the IP Group as an Outbound Message Manipulation Set ('Outbound Message Manipulation Set' parameter), when the IP Group is the destination of the call. If you apply the Manipulation Set as an Inbound Message Manipulation Set ('Inbound Message Manipulation Set' parameter), when the IP Group is the source of the call, the manipulation rule will be overridden by the SIP Group Name.
● When configuring a Message Manipulation rule for manipulating a SIP header, the maximum length (characters) of the header's value in the incoming SIP message that can be manipulated is 4,096.

The following procedure describes how to configure Message Manipulation rules through the Web interface. You can also configure it through ini file [MessageManipulations] or CLI (configure voip > message message-manipulations).

➢ To configure SIP message manipulation rules:
1. Open the Message Manipulations table (Setup menu > Signaling & Media tab > Message Manipulation folder > Message Manipulations).
2. Click New; the following dialog box appears:

3. Configure a Message Manipulation rule according to the parameters described in the table below.
4. Click Apply.

An example of configured message manipulation rules are shown in the figure below:

■ Index 0: Adds the suffix ".com" to the host part of the To header.
■ Index 1: Changes the user part of the From header to the user part of the P-Asserted-ID.
■ Index 2: Changes the user part of the SIP From header to "200".
■ Index 3: If the user part of the From header equals "unknown", then it is changed according to the srcIPGroup call’s parameter.
■ Index 4: Removes the Priority header from an incoming INVITE message.

Message Manipulations Parameter Descriptions

Parameter

Description
General

'Index'

[Index]

Defines an index number for the new table row.

Note: Each row must be configured with a unique index.

'Name'

manipulation-name

[ManipulationName]

Defines a descriptive name, which is used when associating the row in other tables.

The valid value is a string of up to 40 characters.

'Manipulation Set ID'

manipulation-set-id

[ManSetID]

Defines a Manipulation Set ID for the rule. You can define the same Manipulation Set ID for multiple rules to create a group of rules. The Manipulation Set ID is used to assign the manipulation rules to an IP Group (in the IP Groups table) for inbound and/or outbound messages.

The valid value is 0 to 49 for 2-8 GB and 99 for 16-64 GB. The default is 0.

Note: You can configure up to 750 for 2-8 GB and 1,000 for 16-64 GB rules per Manipulation Set ID.

'Row Role'

row-role

[RowRole]

Determines which message manipulation condition (configured by the 'Condition' parameter) to use for the rule.

■ [0] Use Current Condition = (Default) The condition configured in the table row of the rule is used.
■ [1] Use Previous Condition = The condition configured in the first table row above the rule that is configured to Use Current Condition is used. For example, if Index 3 is configured to Use Current Condition and Index 4 and 5 are configured to Use Previous Condition, Index 4 and 5 use the condition configured for Index 3. A configuration example is shown in the beginning of this section. The option allows you to use the same condition for multiple manipulation rules.

Note:

■ When configured to Use Previous Condition, the 'Message Type' and 'Condition' parameters are not applicable and if configured are ignored.
■ When multiple manipulation rules apply to the same header, the next rule applies to the resultant string of the previous rule.

Match

'Message Type'

message-type

[MessageType]

Defines the SIP message type that you want to manipulate.

The valid value is a string (case-insensitive) denoting the SIP message. You can use the built-in syntax editor to help you configure the field. Click the Editor button located alongside the field to open the Editor, and then simply follow the on-screen instructions.

For example:

■ Empty = rule applies to all messages
■ Invite = rule applies to all INVITE requests and responses
■ Invite.Request = rule applies to INVITE requests
■ Invite.Response = rule applies to INVITE responses
■ subscribe.response.2xx = rule applies to SUBSCRIBE confirmation responses

Note: Currently, SIP 100 Trying messages cannot be manipulated.

'Condition'

condition

[Condition]

Defines the condition that must exist for the rule to be applied.

The valid value is a string of up to 200 characters (case-insensitive). You can use the built-in syntax editor to help you configure the field. Click the Editor button located alongside the field to open the Editor, and then simply follow the on-screen instructions.

For example:

■ header.from.url.user== '100' (indicates that the user part of the From header must have the value "100")
■ header.contact.param.expires > '3600'
■ header.to.url.host contains 'domain'
■ param.call.dst.user != '100'

Action

 

'Action Subject'

action-subject

[ActionSubject]

Defines the SIP header upon which the manipulation is performed.

The valid value is a string (case-insensitive). You can use the built-in syntax editor to help you configure the field. Click the Editor button located alongside the field to open the Editor, and then simply follow the on-screen instructions.

'Action Type'

action-type

[ActionType]

Defines the type of manipulation.

■ [0] Add = (Default) Adds new header/param/body (header or parameter elements).
■ [1] Remove = Removes header/param/body (header or parameter elements).
■ [2] Modify = Sets element to the new value (all element types).
■ [3] Add Prefix = Adds value at the beginning of the string (string element only).
■ [4] Add Suffix = Adds value at the end of the string (string element only).
■ [5] Remove Suffix = Removes value from the end of the string (string element only).
■ [6] Remove Prefix = Removes value from the beginning of the string (string element only).
■ [7] Normalize = Removes unknown SIP message elements before forwarding the message.

'Action Value'

action-value

[ActionValue]

Defines a value that you want to use in the manipulation.

The default value is a string (case-insensitive) in the following syntax:

■ string/<message-element>/<call-param> +
■ string/<message-element>/<call-param>

For example:

■ 'itsp.com'
■ header.from.url.user
■ param.call.dst.user
■ param.call.dst.host + '.com'
■ param.call.src.user + '<' + header.from.url.user + '@' + header.p-asserted-id.url.host + '>'
■ Func.To-Upper(Param.Call.Src.Host)

You can use the built-in syntax editor to help you configure the field. Click the Editor button located alongside the field to open the Editor, and then simply follow the on-screen instructions.

Note: Only single quotation marks must be used.